Written by Thomas R. Lawrence (tomlaw@world.std.com), copyright 1993.
Portions copyright Symantec, Inc.
MultiFile Dialog box copyright Manuel Veloso.
DISTRIBUTION RESTRICTIONS:
- This package must be distributed UNALTERED, in its ENTIRETY.
- This package may NOT be distributed with COMMERCIAL software.
- NO FEE may be charged for the distribution of this package if the intent is to make a profit. Online services may charge a REASONABLE fee for system usage while downloading. NON-PROFIT organizations may charge a REASONABLE fee to recoup overhead for distributing media.
This program requires System 7.
The UNIX side seems to work on HPUX, SunOS, and Ultrix. It also seems to work via rlogin and telnet sessions from both an Annex and a NetBlazer. It still will NOT work via a normal telnet session from one machine to another. It also still requires GCC to compile.
If you have any improvements to the UNIX side of things PLEASE send them to me and I'll include them in the next version.
• Acknowledgements
Thanks to Michael Khaw (khaw@parcplace.com) for supplying a real makefile and for feedback on improving the interface.
• What is MultiSession?
MultiSession is a special terminal program that allows you to have up to 15 windows open over a single serial connection. Each window behaves independently of the others. This means you can upload, download, read news, FTP, and get useful work done all at the same time. The program will communicate with another MultiSession running on another Macintosh, or with a UNIX host, using the special UNIX MultiSession server program.
• First Look at MultiSession
You will notice that this program is simple. Very simple. Some would say spartan. In short, a TeachText of terminal programs. Why? I intended the program to solve a very specific problem: downloading takes a long time. I wanted to be able to read news or talk or get Something, Anything done while downloading. Therefore, you won't see scripts or macros. There is no communications toolbox support. There is no support for "standard" file transfer protocols (naturally, there IS a upload/download protocol, but it isn't standard). If you want these things, you are probably better off using a full-featured terminal program like ZTerm or one of the commercial ones.
(You're probably wondering, "So, what CAN the program do?")
• General Stuff
When you start the program, there is a dialog box asking for baud rate, parity, which serial port, and all that stuff. There are two text boxes worth noting:
Init String
and
Dial String
Init String is the modem initialization string. The program expects the modem to respond to this string with "OK"; in other words, it wants a Hayes compatible modem. Of course, you can leave this blank and it will be ignored. You can put whatever initialization you want in this box. (e.g. if you want to modem to shut up, you can say "at m".) If the modem does not respond with "OK", then the program will become confused and just sit there, waiting. Don't worry, it hasn't crashed. Just quit the program and restart it, or abort the automatic dialin using the "Abort Autodial" option from the Control menu.
Dial String is a modem command to dial the desired phone number, like "atdt 555-1234". The program has a primitive redial function: If the modem responds to the string with "BUSY", "NO CARRIER", or "NO DIALTONE", the program will send it again. And again. And again. Ad infinitum. Of course, the moment it gets anything containing any sort of "CONNECT" message, it will stop trying to dial and allow you to type.
If you leave both text boxes empty, the program won't attempt to initialize the modem or redial; instead, you can type immediately. This is useful in case something crashes (certainly not MY program... :-) ) or you want to send the commands directly to the modem yourself, or you aren't using a modem, or...
You can save the settings in a file using the "Save As..." button. When you double click on the file, MultiSession will be automatically opened and whatever settings you had saved will be reloaded into the dialog box.
When you are ready to try to connect, click the "Connect" button.
• Terminal Emulation and All That
Once you get online, the remote system will probably ask you what type of terminal you are using. MultiSession emulates enough VT102 to fool UNIX, so you can say "vt102".
I've included a keyboard layout document which uses the Option key to emulate a meta key. I tried to incorporate this into the program itself, but the dead keys in the keyboard mapping from the System file interferred to make it unusable. So here is the keyboard layout I prepared. Just drag it into your System file. Whenever you need meta keys, use the Keyboard control panel to switch to it. The catch: be sure to switch back to your normal keyboard layout when you are done or else Option keys will behave very strangely in other applications. (The technical reason that I couldn't incorporate this in the application itself is that I wouldn't get a keyboard event for Option-i or similar dead keys until another character had been pressed, even if I mapped the key codes myself using KeyTrans. If you know of a workaround, please contact me!)
If you are good with ResEdit, you can enable the Keyboard Menu so that you can quickly change keyboard layouts without opening the Keyboard control panel. Open the 'itlc' resource number 0 in the System file and locate the "Always Show Keybd. Icon" option. Click the "1" radio button, close the System file, and restart. This will enable a small keyboard menu which will show up between the balloon help and program menus. (This information from a tip sent by Dominik Hoffmann to MacUser's "Tip Sheet" column, page 205, June 1993, Volume 9, Issue 6.)
If your system expects the ASCII "DEL" character (code 127) instead of the ASCII "BS" character (code 8) for deleting, you can select the menu option "Delete is ASCII 127 instead of ASCII 8" from the "Terminal" menu. If you need to use the alternate delete code only briefly you can hold down the command key while pressing delete.
• Log Windows
The program provides a log window for the root terminal window and any session you might open in 'MultiSession' mode, which you can view by choosing "Show Log Window" from the Terminal menu. The log window saves as many lines off the top as it can fit in memory. If there is no memory, it starts getting rid of the oldest saved lines to make room for the new ones. You can increase the available memory by choosing "Get Info" from the File menu in the Finder and increasing the allocation. I've run the program in as small a partition as 384K (for debugging) but this doesn't save very many lines off the top, and I don't suggest it. The default setting is 640K. You can set it as large as you want, for example 5120K if you want to save a WHOLE LOT of lines.
The Log Window has a search capability. Choose "Find" from the Terminal menu and you will be asked for the search string. If you have already specified a search string, you can choose "Find Again" to find the next occurrence of the string. Searching begins at the current selection or at the beginning if there is no selection. If the string can't be found or doesn't occur after the current selection, the program will beep and reset the search so that it will start over at the beginning the next time you choose "Find Again".
Finally, the scroll bars support "active scrolling" which means the window will be redrawn as you drag the scroll box. To make the scroll bars behave like normal ones, hold down the option key before clicking on the scroll box.
• Timer
There is a timer which keeps track of the amount of time you've been on line. The timer starts the moment the program tries to dial. If the line is busy, the timer is reset when the program redials. The timer is shut off when the string "NO CARRIER" appears in the root window.
It is sometimes difficult to tell when the modem has really hung up. For instance, if someone mailed you a message, they could include "NO CARRIER" in the message and stop the counter. For that reason, the program will not stop the timer unless at least half a second passes without receiving any more characters. With this in mind, the timer should behave reasonably reliably, but don't depend heavily on it. If you are worried that the timer might be stopped prematurely, there is a menu option which will prevent "NO CARRIER" from stopping the timer; in this case, you'll have to stop it yourself if you want to see exactly how long you've been on line.
• The UNIX Part of MultiSession
In order to do anything useful when connected to a UNIX host, you need to compile the UNIX MultiSession server. Somehow get the "multisession104unix.tar.Z" file into a directory somewhere.
type "uncompress multisession104unix.tar.Z" to decompress it.
type "tar xf multisession104unix.tar" to extract the archive.
type "cd ms_dir" to go to the directory.
type "make" to build the programs.
The resulting files are:
MultiSession (this is the server)
SendFile (use this to download)
ReceiveFile (use this to upload)
Title (use this to change a window's title)
You can delete all the other files.
Note: This program uses the BSD-UNIX interface (sort of). I have no idea what systems it will successfully compile on, other than that it was developed under Ultrix. If the compiler complains about something, try deleting it. (Always good advice. :) ) It's probably just an #include file that couldn't be found, anyway. If, after deleting a few things, the problems seem to be getting worse, it's probably best to just chuck the program.
If you are a UNIX programmer, please look at my code and see if you can improve it. If you have any neat enhancements, bug corrections, or anything else, please send them to me so I can include them in the next version. (By looking at my code, it should be fairly obvious that I am a Macintosh programmer, not a UNIX programmer.)
• Running MultiSession
A general problem with UNIX is that not all 8 bits of each character are transmitted. On some systems only 7 bits are transmitted. Usually, to get the full 8 bits, you have to log in with a special command. For example, when I log in from our NetBlazer to one of the workstations, I must type "rlogin -8 -noesc <hostname>".
MultiSession allows you to specify how many bits wide the connection is. If you are certain you have an 8-bit connection, simply start the program by typing "MultiSession". If you have a 7-bit connection, start the program by typing "MultiSession 7". If you don't know how many bits wide the connection is, you can try using an 8-bit connection. If you can't open any windows, then you probably have a 7-bit connection. A word of warning: Some connections may appear to be 8-bit but aren't. For example, the NetBlazer I use supposedly established an 8-bit connection with "telnet -b <hostname>". All 8 bits were transmitted correctly except for two certain characters, where the 8th bit was stripped! If your system is like this, the connection might appear to work for a while and then suddenly stop working (destroying whatever you were working on). You can always use "MultiSession 7" if you don't want to take the risk. (The advantage of using the full 8-bits is that it's faster.) If "MultiSession 7" doesn't work, then you have real problems.
When you run the UNIX MultiSession server, you'll see a message, and then MultiSession on your Macintosh will automatically enter 'MultiSession' mode. If a line of garbage shows up, don't worry about it. If garbage continues to pour out that means the automatic signal was not received (perhaps due to line noise?); if this happens, choose '"Go To MultiSession Mode" from the Control menu. The program will automatically open a window for you in a couple of seconds.
If, for some reason, you need to go back to 'normal' terminal mode without ending the current session, choose the menu option again (now worded "Go To SingleSession Mode"). You can then escape to your annex or do whatever you want. You can return to MultiSession mode by getting back to the server program (so that you can see it printing garbage again) and choose the menu option "Go To MultiSession Mode". Within a couple of seconds, everything will resume as if nothing had happened.
If, for some reason, you lose contact with the server, or the Macintosh MultiSession program crashes, all is not lost. If you can somehow get back online to the point where you can see garbage pouring out, choose "Go To MultiSession Mode" and then choose "Reestablish Broken Connection" from the Control menu and the program will attempt to resynchronize with the UNIX server. This process usually takes about 10 seconds. A small amount of data actually being sent when the connection was broken may be lost, but this shouldn't affect file transfers. If 30 seconds have passed and you still can't type any commands or create new windows, you will probably have to restart. Note that if you do NOT reset the Macintosh side, the windows will remain on screen and file transfers in progress in them will resume correctly. If you do reset the Macintosh side, the file transfers will be aborted.
Note that the UNIX MultiSession server can't be killed by Control-C, so if things get really wedged, you may have to hang up (unplugging the modem is one sure way of doing this!) and connect again. Naturally, this destroys whatever you were doing. Hopefully my program is free enough of bugs that this won't happen.
To open a new command shell, choose "New Session" from the File menu. If the remote system is able to open the new shell, a window will soon pop up, otherwise an alert box will appear, saying the remote system was unable to open a new session. You can close a session by choosing "Close Session" or clicking in the window's close box. You can also close a window by typing "exit" or "logout" on the command line. Please note that closing a window kills the command shell for that window and any program that is running in it. It's best to quit any programs before closing the window.
If you want to terminate the server, save whatever you are doing in the various windows and choose the "Kill Remote Server..." menu option. Click "OK" and wait for a few seconds so that the remote server gets the message. As soon as this happens, the server will automatically signal the Macintosh MultiSession to return to 'normal' terminal mode and print the message "Done" out. If this does not happen after about 10 seconds, the signal may have been destroyed by line noise. In this case, choose "Go To SingleSession Mode" from the Control menu and then choose "Reset MultiSession Controller..." to reset the inner workings of the Macintosh program.
• The "Title" Utility
The program called "Title" changes the title of the current window. To use it, type
Title "<New window title>"
The quotes are necessary if you have spaces in the new title. You can also change the window's title with the "Rename Window" menu option on the Windows menu.
• File Transfer
MultiSession comes with an upload and a download program, which can be used from any MultiSession window as well as in 'normal' terminal mode.
Downloading: (from them to you)
To get some files, you specify the file names you want to download on the command line. If you want to use the 7-bit protocol, you need to specify that by putting a "-7" as the first word on the command line. So,
will download the specified files using 7 bit encoding.
PLEASE NOTE: SendFile needs a "-7" instead of just "7" as used by the MultiSession program, so that it doesn't get confused with a filename. Also remember, the 7-bit option has to be first on the command line.
So where do these files go, you ask? Well, I didn't know how to make a "choose destination folder" dialog box, so I kludged something up. If you put a folder or an alias of a folder named "Download Folder" in the same folder as the MultiSession program, the files will be put there. (Note, if you use an alias, the alias must be named "Download Folder", but the actual folder it refers to can be named anything you like.)
Uploading: (from you to them)
Things are different with "ReceiveFile". This time, you specify the number of bits on the Macintosh side, but ONLY IF NECESSARY. Don't worry, it will ask you if it isn't sure. For instance, if you checked "7-bit" in the initial dialog box, it won't bother asking, and if you are running in MultiSession mode, it will use 8-bits since MultiSession mode ensures an 8-bit wide channel for each window you open. Any other time it will give you a dialog box and let you choose which encoding you want to use.
To Upload, here's what you do:
Type "ReceiveFile" with no arguments. This will make the remote system wait for the data.
Choose "Send Files..." from the File menu. A very nice dialog box (which I didn't write; Manuel Veloso did!) will appear allowing you to choose some combination of files to send to the remote system. Click "Done" when you are finished and, if necessary, it will ask you for the number of bits to use. Then it will start sending...
About my file transfer protocol:
The protocol is designed to be as fast as ZMODEM when running under relatively error-free conditions. In the worst case, it will start to act like Kermit using 1k packets. I was going to implement ZModem, but I took one look at the paper on it and said "bleah". Maybe in a future version. Also, if a file comes out corrupted, try transferring it again. If it works fine the second time, please yell at me!
• MacLayers vs. MultiSession
So which one is better? Well... It depends on what you're going to do. To help you understand when one will do better than the other, I'll describe briefly how both programs work.
MacLayers works by sending data as a raw stream of characters with codes embedded occasionally describing which window should be receiving the data. It is fast: it maximizes bandwidth use, has little overhead, and is simple. However, it provides no error correction or flow control.
MultiSession sends packets which are partitioned into fields containing data destined for various windows. Each packet has a CRC32 check sequence, a destination description, and a packet ID number, and is encoded with a 7-bit or 8-bit scheme for transport over less than transparent connections. It is slow: it can't fully use the available bandwidth, has large overhead (to encode/decode packets), and is quite complex. However, it provides error correction to ensure that ALL data gets through correctly, and it allows data to be received simultaneously on several windows, even if the senders are all going full blast. So...
When to use MacLayers:
-If you have a relatively error-free connection, or a good error-correcting modem.
-If you don't need to print text on many windows simultaneously (most people really only have one "active" window; the others just sit there).
-If you have a slow modem (i.e. 2400 baud. See next section).
When to use MultiSession:
-If you have an error-prone connection. Or a bad modem.
-If you do a lot of simultaneous full-speed data transfers, or upload and download at the same time.
-If you don't mind a bit of delay when you type.
• MultiSession and Fancy Modems
First, this program does NOT work well at 2400 baud. Yes, you can choose 2400 baud in the configuration dialog box, but be warned: at 2400 baud, the throughput rarely exceeds 50% of the raw channel capacity, which means at best you'll be effectively doing 1200 baud.
MultiSession does not seem to like connections with error correction or data compression. Specifically, there is a high "latency", which means every character you type takes a long time to go through the system. For example, at 9600 baud with MNP5 data compression, it takes more than 2 seconds for a character to be echoed after being typed. This is because the modems buffer the data and then compress the whole buffer before sending the data on its way. This means large delays are introduced on both ends while the buffers fill up. This effect may not be as bad at very high speeds (such as 14400 + V42.bis) but I don't have the equipment to test that.
Basically, I recommend using a direct connection (my modem allows this with "at\n") if you will be doing interactive work, such as text editing. Also, to keep the modem from buffering the data and introducing delays, you should set the baud rate to be the same as the rate you will connect to the remote modem at. If you really need to get a lot of data through in a hurry (i.e. downloading that 5 megabyte file), I suggest using all the compression you can and doing the download in 'normal' terminal mode.
• Source Code and All That
If you want to write your own compatible server or client, DO NOT USE THE SOURCE CODE I'VE PROVIDED AS A BASIS!!! Why? Because it's incomplete. The server is only one side of the story; there are essential things the client does which you can't figure out from the server source code alone. If you want to do this, ask me and I'll send you a description of the connection protocol, and maybe even the source code for the core of the client (i.e. the data transceiver). Then you can struggle with the same timing, dynamic bandwidth measurement, and latency issues that I have. (It isn't a pretty sight.)
If you want to use my file transfer protocol (I doubt anyone would since there's better available, but...), I think you can get everything you need to know from the source code for SendFile and ReceiveFile. If not, then ask me.
If you make your own server or client, I'd like you to print out a message stating that the program is a "modified" version of MultiSession, or use a different name.
If you write a program derived from my routines, I don't care what you call it. However, it would be nice if you gave me some credit somewhere.
• Warrantee
There isn't one. I'm not responsible for any data you lose while using my program. After all, you don't have to pay me anything. And if you sued me, you'd be disappointed by the pittance you'd get out of me, and I would have to drop out of college. Words of advice: don't use my program for important things until you are confident it is stable.
• Parting Words
I hope this program is useful to somebody. Please contact me if you have
1) Suggestions
2) Bug reports
3) Comments
4) Anything
Thomas R. Lawrence
tomlaw@world.std.com
This address will remain valid for a LONG LONG time, but please be patient since I don't log in every day.
